Termight · Spec Workspace Redesign Implementation Brief

v1 · engineering handoff Reference prototype: Spec Workspace.dc.html

Spec Workspace Redesign

A build-ready specification for rebuilding the Specs page so a new user can move a spec through all five workflow stages without hitting the cramped, unscrollable panel that exists today.

1 · Why we're changing this

The current Specs page renders the entire workflow — identity, stepper, the active stage's editor, the criteria ledger, and evidence candidates — inside a single nested scroll region (termight-spec-content-scroll). That region is short, so the structured editor is clipped to a few pixels of visible height and is effectively impossible to scroll or use. The page also shows everything for every stage at once, which reads as busy and gives a new user no obvious path.

Goals. (1) Remove the nested mini-scroll — the workspace scrolls as one natural column. (2) Make the five-stage workflow the primary navigation and show only the active stage. (3) Keep the primary action reachable at all times. (4) Be legible to a first-time user: one clear "what unlocks next" line per stage.

2 · Where this lives

This is a rework of the existing Specs section — not a new route. All work happens in the agents-specs view and its model.

File	Role
frontend/app/view/termightconfig/termightagentsspecs.tsx	Section render. Rebuild the layout described in §3–§4 here.
termightagentsspecs-model.ts	Jotai model: problems, autosave, spec JSON. Reuse as-is.
speccriterialedger.ts	buildLedgerCriteria / merge-gate. Feed the Verify stage.
frontend/tailwindsetup.css	Design tokens (§6). Use these vars — do not hardcode new colors.

The existing props, atoms, autosave, AI-draft handlers, and workflow-view state (AgentSpecWorkflowView) all stay. This is primarily a layout and information-hierarchy change; the data plumbing already exists.

3 · Page architecture

Top to bottom, the Specs pane is a fixed shell with a single scrolling body. Only the Workspace body scrolls; the header and action bar are pinned.

1. Specs header (pinned). Serif "Specs" title, project picker, spec count, Sync, primary "New spec". Unchanged from today.
2. Identity bar. Spec name, status badge, criteria summary, one mono meta line (spec · status · root · save state), and a single problems chip (expandable). Remove the duplicate problems pill and the "Spec file — derived" disclosure from the header row.
3. Stepper hero. Full-width card: five numbered nodes (Draft → Clarify → Plan → Launch → Verify) joined by connectors, each clickable. Completed steps show a check and green connector. Below a divider: the active stage's gate sentence with a status dot, and — when the gate is satisfied — a "Continue → {next}" button.
4. Stage header. Uppercase green kicker, serif heading, one-line description, and a status pill. Copy per stage in §4/§7.
5. Stage body: a two-column grid, minmax(0,1fr) 300px. Left = the active stage's working area (§4). Right = a persistent Readiness card plus one stage-specific helper card.
6. Action bar (pinned, bottom). Primary stage action (green) + "Save spec" + a "{status} · Step N of 5" locator.

Container: center the body at max-width: 1120px (there is already a --container-spec-wide: 1180px token). Collapse the two-column grid to one column below ~900px.

4 · The five stages

Each stage renders only when it is the active workflowView. Layout is consistent across stages (working column + right helper), so the page stays learnable.

Draft — shape the contract

• Working area: "Spec draft" card with Goal and Problem textareas (bound to updateSpecString). Below, an Acceptance criteria card: one editable row per criterion (AC-00N id + text + remove) and a dashed "+ Add criterion" button.
• Helper: Draft sources counts (sessions / capsules / eval runs / Knowledge).
• Gate: unlocks Clarify when goal is non-empty and ≥1 non-placeholder criterion exists (draftGateReady).
• Primary: "Refine with AI" (or "Draft with AI" when empty).

Clarify — resolve ambiguity

• Working area: "Question inbox" — each open_question is a row with its id, a status pill (open / assumption / resolved / deferred), an impact note, and editable text. "Add question" appends a row. A second card lists assumptions & non-goals.
• Helper: Clarify summary (open / assumptions / resolved counts).
• Gate: Ready when zero open questions remain.
• Primary: "Mark ready" → sets spec status to ready.

Plan — assemble the plan

• Working area: "Workflow plan" — numbered stages with a ready/blocked pill; and the accepted acceptance criteria carried in read-only with a "planned" tag.
• Helper: Context pack — item count, eval fixtures/targets, and a token-budget progress bar (estimate / budget · fits).
• Gate: Launch unlocks when a workflow stage is ready; otherwise "Build the plan to unlock Launch."
• Primary: "Build plan" / "Rebuild plan".

Launch — hand off to an agent

• Working area: the next ready stage with an inline "Launch" button, then a read-only payload preview — goal, criteria list, write scope, stop conditions — exactly what the agent session receives.
• Helper: Launch checklist (spec ready · plan built · context fits · handoff gate clear).
• Gate: "Runs in a fresh worktree · appears in Agents" once spec is ready; else "Mark the spec ready before launching."
• Primary: "Launch stage N".

Verify — close the loop

• Working area: four count tiles (required / verified / waived / missing) then an evidence ledger — each criterion mapped to its evidence ref with a verified/waived/missing pill. Source from buildLedgerCriteria.
• Helper: Merge gate summary (same four counts).
• Gate: "All required criteria satisfied — merge gate open" when missing = 0.
• Primary: "Verify evidence".

5 · State & interaction

• Active stage is the existing workflowView state. Clicking a stepper node or "Continue →" calls selectWorkflowView(id). Preserve getPreferredAgentSpecWorkflowView for the initial view.
• Gate + suggestion come from the existing stageGateSentence and suggestedWorkflowView. Dot is green when ok, amber otherwise.
• Problems use model.problemsAtom. Show one chip: neutral "0 problems" or amber "N problems" expanding to the list. Chip and gate must update live as the user edits.
• Autosave label and save-path stay wired to the model; surface the state in the meta line, keep the editable save path behind a small disclosure.
• Structured editor: the criteria/goal/problem inputs disable when structuredEditorDisabled. Do not keep it mounted-but-hidden across stages the way it is today; render it only inside Draft.
• Action bar primary maps to runStagePrimaryAction(); label + disabled from stagePrimaryActionLabel / stagePrimaryDisabled.

6 · Visual tokens

Use the existing CSS variables from tailwindsetup.css. Reference values below.

Token	Value	Use
--color-accent	rgb(88,193,66)	Current step, primary button, "ok" gate
--color-attn / warning	#e3a94e	Problems chip, blocked gate, "missing"
--color-error	#e0563c	Blocked stage, autosave error
--color-foreground / secondary / muted	#f7f7f7 / #b9c9bc / #8aa08e	Text hierarchy
--color-surface0/1/2	#0b0f0c / #121812 / #18211a	App bg, cards, inputs
--color-border / linefaint	rgba(167,199,176,.14)	Card borders, dividers, connectors
--radius	8px	Cards 12–14px, inputs/pills 8–9px
--font-display / sans / mono	Iowan · Inter · Hack	Title serif; body sans; ids/meta mono

Type floor: body ≥ 12.5px, ids/meta mono 11px. Never smaller. Green primary buttons use near-black text (#0a1408) for contrast.

7 · Copy reference

These strings already exist in the view (stageIntro, stageGateSentence). Keep them.

Stage	Kicker	Gate (not-ready)
Draft	Draft workspace	Clarify unlocks when the draft has a goal and one criterion
Clarify	Clarification inbox	N open questions block Ready
Plan	Planning workbench	Build the plan to unlock Launch
Launch	Launch console	Mark the spec ready before launching
Verify	Verification ledger	N criteria block the merge gate

8 · Acceptance criteria

1. No nested/inner scrollbar in the workspace: the whole body scrolls as one column; the structured editor is fully usable at any window height.
2. Exactly one stage's working area is visible at a time; switching stages via the stepper or "Continue →" swaps it with no layout jump.
3. The primary action and "Save spec" are visible without scrolling, at every window height (pinned action bar).
4. Editing the draft updates the problems chip, readiness card, and gate sentence live.
5. Stepper reflects progress: completed steps show a check + green connector; current step is accent; future steps are muted.
6. All existing behavior — autosave, AI draft/refine, mark-ready, build-plan, launch, verify — remains wired through the current model/handlers.
7. Colors, type, and spacing come from the existing tokens; no new hardcoded palette.
8. Below ~900px the two-column stage body collapses to one column and the stepper stays legible.

9 · Out of scope & open questions

• Out of scope: the raw JSON spec editor, the spec-list/inbox sidebar, and eval-runner wiring — leave their current behavior.
• Open: should the Plan stage's context / workflow / evals / evidence sub-panels remain as internal tabs, or split into their own stepper sub-steps? Defaulting to internal cards for now.
• Open: confirm the mobile/narrow breakpoint — the desktop app rarely goes below 900px, so single-column is a safety net, not a primary target.

Interactive reference: open Spec Workspace.dc.html and click through the five steps — it is the visual and behavioral source of truth for this brief.